        VADV-PHP DEVELOPMENT DOCUMENTATION                           05-08-2004
        ----------------------------------

        INTRODUCTION
        ------------

        VADV-PHP was created for three main purposes:

            1) Allow me to learn PHP.
            2) Provide a web interface for Virtual Advanced.
            3) Provide a development environment for others to use.

        Since this is a project I began while learning the language, it is
        not perfect and it could of been managed a lot better. Since this
        project is merely a hobby and I'm not getting paid or anything, there
        is little chance of me starting over and creating a better system.

        With that said, I have provided an extensive set of functions that allow
        anyone to create their own applications that will work with Virtual
        Advanced. Even the complete beginner can develop easily. Plus for the
        beginner there is no object oriented programming to have to learn.

        The whole project started off with me writing the various functions to
        allow anyone to write VADV web applications using PHP. I wrote the
        various web-bbs pages merely as a demonstration of the functions. As I
        said above, they could be done much better.

        This documentation was written to explain the basics of creating a
        VADV-PHP application. I will also give any hints or tips that I think
        of that may be of use. Lets get started...


        THE INCLUDE DIRECTORY
        ---------------------

        The heart and soul of VADV-PHP are the files that reside in the
        'include' directory. These are files that contain all of the needed
        functions to interface PHP with VADV. No other files that are included
        in the package are needed and could be totally scrapped.

        Each file in this directory has the extension of inc.php which I use to
        designate a file that is intended to be included within a script. If you
        execute any of the inc.php scripts then you will get no output.

        The different include files contain functions that pertain to a
        particular VADV data file. For example, va-doors.inc.php has functions
        to work with the doors.cfg file. There are a few special include files
        however which don't work with any particular data file. These files are
        (with a short description):

            common.inc.php - Contains settings that pertain to ALL VADV-PHP
                scripts, including php.ini settings.
            forms.inc.php - Contains various forms used in VADV-PHP scripts,
                such as the login form or new user registration form.
            va-database.inc.php - Contains functions dealing with the VADV
                databases.
            va-functions.inc.php - Contains various functions that are vital
                to VADV-PHP's operation.
            va-loginauth.inc.php - This script does user authentication.

        The most important include file (and the only one required to be
        included in a VADV-PHP script) is va-functions.inc.php. This script not
        only contains vital functions for VADV-PHP, it also does the
        initializing for settings, sessions, paths and many other things. When
        you include va-functions.inc.php into a script, the following scripts
        are directly or indirectly included as well:

            common.inc.php
            va-syspaths.inc.php
            va-loginauth.inc.php
            va-misc.inc.php
            va-stats.inc.php
            va-userfile.inc.php

        But even though those files are automatically included in every
        VADV-PHP script, it is recommended that if your script needs something
        from one of those scripts that you include it after the
        va-functions.inc.php script. Not only does this ensure that it is
        included, it is also a good reminder of what functions your script
        might be using and has access to.

        To ensure that these files are included only once per script, use the
        "require_once" function at the beginning of your scripts.


        INCLUDE_DIR.PHP
        ---------------

        You may notice that in each directory there is a file named
        include_dir.php. This script simply sets the variable $includeDir to
        the relative path (or absolute path) to the include directory. This
        allows you to have the include files in their own directory and allows
        you to have a directory structure for different parts of a project.

        The include_dir.php file must be the first file included in your script.
        This is needed to tell your script where to go to include the
        va-functions.inc.php script. For example:

            require_once('include_dir.php');                    
            require_once($includeDir . 'va-functions.inc.php'); 

        This code includes the include_dir.php file which sets $includeDir, then
        uses $includeDir to tell where va-functions.inc.php is located so it
        can be included.


        DEBUGGING
        ---------

        By default whenever an error occurs during the execution of a VADV-PHP
        script, a basic error message is displayed stating that "an error
        occurred" and that "the site administrator has been notified." On beta
        releases, an email will be sent to bugs@vadvphp.com with information to
        help debug the error that occurred. On official releases, this is
        disabled and no email is sent. If you would like to participate in the
        debugging process of an official release, you can enable it by editing
        the va-functions.inc.php script and changing the variable $DEBUG_MAIL
        to "TRUE".
        
        When you are developing your own VADV-PHP scripts, you will want to
        disable the error handling completely or create your own error
        handling functions. To disable error handling, do the following two
        steps.
        
        1) In common.inc.php, change "ob_start('ob_handler');" to "ob_start();"
        2) In va-functions.inc.php, comment out the line that contains
           "set_error_handler('CustomErrorHandler');".


        CONCLUSION
        ----------

        This documentation is not complete.